<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">











<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Apache log4j 1.2 - Frequently Asked Technical Questions</title>
    <style type="text/css" media="all">
      @import url("./css/maven-base.css");
      @import url("./css/maven-theme.css");
      @import url("./css/site.css");
    </style>
    <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
          </head>
  <body class="composite">
    <div id="banner">
                  <a href="../../" id="bannerLeft">
    
                                            <img src="images/ls-logo.jpg" alt="" />
    
            </a>
                        <a href=".." id="bannerRight">
    
                                            <img src="images/logo.jpg" alt="" />
    
            </a>
            <div class="clear">
        <hr/>
      </div>
    </div>
    <div id="breadcrumbs">
          
  

  
    
  
  
    
            <div class="xleft">
        Last Published: 2010-03-30
                          |   
                <a href="http://www.apache.org/" class="externalLink">Apache</a>
                &gt;
      
                <a href="../../">Logging Services</a>
                &gt;
      
                <a href="../">log4j</a>
                &gt;
      
                <a href="http://logging.apache.org:80/log4j/1.2/" class="externalLink">1.2</a>
                          </div>
            <div class="xright">      
  

  
    
  
  
    
  </div>
      <div class="clear">
        <hr/>
      </div>
    </div>
    <div id="leftColumn">
      <div id="navcolumn">
           
  

  
    
  
  
    
                   <h5>Get log4j 1.2</h5>
            <ul>
              
    <li class="none">
                    <a href="download.html">Download</a>
          </li>
              
    <li class="none">
                    <a href="changes-report.html">Changes</a>
          </li>
              
    <li class="none">
                    <a href="license.html">License</a>
          </li>
          </ul>
              <h5>About log4j 1.2</h5>
            <ul>
              
    <li class="none">
                    <a href="index.html">What is log4j?</a>
          </li>
              
    <li class="none">
              <strong>FAQ</strong>
        </li>
              
    <li class="none">
                    <a href="roadmap.html">Roadmap</a>
          </li>
          </ul>
              <h5>Community</h5>
            <ul>
              
    <li class="none">
                    <a href="mail-lists.html">Mailing Lists</a>
          </li>
              
    <li class="none">
                    <a href="issue-tracking.html">Issue Tracking</a>
          </li>
          </ul>
              <h5>Development</h5>
            <ul>
              
    <li class="none">
                    <a href="source-repository.html">Repository</a>
          </li>
              
    <li class="none">
                    <a href="jxr.html">Cross Reference</a>
          </li>
              
    <li class="none">
                    <a href="dependencies.html">Dependencies</a>
          </li>
              
    <li class="none">
                    <a href="integration.html">Continuous Integration</a>
          </li>
          </ul>
              <h5>Documentation</h5>
            <ul>
              
    <li class="none">
                    <a href="manual.html">Introduction</a>
          </li>
              
    <li class="none">
                    <a href="apidocs/index.html">JavaDoc</a>
          </li>
              
    <li class="none">
                    <a href="publications.html">Publications</a>
          </li>
              
    <li class="none">
                    <a href="http://wiki.apache.org/logging-log4j" class="externalLink">Wiki</a>
          </li>
          </ul>
              <h5>Apache</h5>
            <ul>
              
    <li class="none">
                    <a href="http://www.apache.org" class="externalLink">Home</a>
          </li>
              
    <li class="none">
                    <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsorship</a>
          </li>
              
    <li class="none">
                    <a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a>
          </li>
              
    <li class="none">
                    <a href="http://www.apachecon.com" class="externalLink">Conferences</a>
          </li>
          </ul>
                                           <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
            <img alt="Built by Maven" src="./images/logos/maven-feather.png"></img>
          </a>
                       
  

  
    
  
  
    
        </div>
    </div>
    <div id="bodyColumn">
      <div id="contentBox">
        <div class="section"><h2><a name="top">Frequently Asked Technical Questions</a></h2>
<ol type="1"><li><a href="#a1.1">What is log4j?</a></li>
<li><a href="#a1.2">Is log4j a reliable logging system?</a></li>
<li><a href="#a1.3">What are the prerequisites for log4j?</a></li>
<li><a href="#a1.4">What are the features of log4j?</a></li>
<li><a href="#a1.5">Is there example code for using log4j?</a></li>
<li><a href="#a1.6">What documentation should I read to learn more about
      log4j?</a></li>
<li><a href="#a1.7">Is log4j thread-safe?</a></li>
<li><a href="#a1.8">What does log output look like?</a></li>
<li><a href="#a1.9">Why should I use log4j when JDK 1.4 already ships with a
      logging API?</a></li>
<li><a href="#a2.1">What are <em>Loggers</em>?</a></li>
<li><a href="#a2.2">How can I change log behavior at runtime?</a></li>
<li><a href="#a2.3">What is the fastest way of (not) logging?</a></li>
<li><a href="#a2.4">Are there any suggested ways for naming loggers?</a></li>
<li><a href="#a2.5">How do I get the fully-qualified name of a class in a static block?</a></li>
<li><a href="#a2.6">Can the log output format be customized? </a></li>
<li><a href="#a2.7">What are the configurable options for <code>FooBarAppender</code>?</a></li>
<li><a href="#a2.8">What is the recommended way of migrating from
      java.util.logging to log4j?</a></li>
<li><a href="#a2.9">Is it possible to direct log output to
      different appenders by level? </a></li>
<li><a href="#a2.10">What does the Windows NT Event Viewer complain about
      missing descriptions for my event messages when I use the
      <code>NTEventLogAppender</code>?</a></li>
<li><a href="#a2.11">Why can't I map my logger names to the loggers that
      appear in the NT Event Log when I use the
      NTEventLogAppender?</a></li>
<li><a href="#a2.12">Are there suggested approaches for logging in JSP pages?</a></li>
<li><a href="#a3.1">Can the outputs of multiple client request go to
      different log files?</a></li>
<li><a href="#a3.2">Logger instances seem to be create only. Why isn't
      there a method to remove logger instances?</a></li>
<li><a href="#a3.3">How do I get multiple process to log to the same file?</a></li>
<li><a href="#a3.4">How about the timesamps of events generated by multiple
      processes across multiple hosts (possibly across multiple
      timezones)?</a></li>
<li><a href="#a3.5">Why can't log4j find my properties file in a J2EE or WAR
      application?</a></li>
<li><a href="#a3.6">Is there a way to get log4j to automatically reload a
      configuration file if it changes?</a></li>
<li><a href="#a4.1">Why should I donate my extensions to log4j back to the
      project?</a></li>
<li><a href="#a4.2">What should I keep in mind when contributing code?</a></li>
<li><a href="#duplicate-messages">Why am I getting multiple copies of messages in my log file?</a></li>
<li><a href="#custom-level">How do I add a custom level?</a></li>
<li><a href="#unload">Why does log4j throw a NullPointerException or
              print a message about NOPLoggerRepository
              when shutting down or restarting under Tomcat or during a shutdown
              hook?</a></li>
<li><a href="#rfa">Why isn't my rolling file appender properly rolling files or why does
              logging events get written to the old log file?</a></li>
<li><a href="#noconfig">
              Why do I see a warning about "No appenders found for logger" and
              "Please configure log4j properly"?
          </a></li>
<li><a href="#sysprops">What system properties are checked by log4j?</a></li>
</ol>
</div>
<dl><dt><a name="a1.1">What is log4j?</a></dt>
<dd>	<p>log4j is a tool to help the programmer output log statements to a
	variety of output targets.
	</p>

	<p>In case of problems with an application, it is helpful to
	enable logging so that the problem can be located. With log4j
	it is possible to enable logging at runtime without modifying
	the application binary.  The log4j package is designed so that
	log statements can remain in <i>shipped</i> code without
	incurring a high performance cost. It follows that the speed
	of logging (or rather not logging) is capital.
	</p>

	<p>At the same time, log output can be so voluminous that it quickly
	becomes overwhelming. One of the distinctive features of log4j is the
	notion of <i>hierarchical loggers</i>. Using loggers it is
	possible to selectively control which log statements are output at
	arbitrary  granularity.
	</p>

	<p>log4j is designed with three goals in mind:
	reliability, speed and flexibility. There is a tight balance
	between these requirements. We believe that log4j strikes the
	right balance.
	</p>
<table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a1.2">Is log4j a reliable logging system?</a></dt>
<dd><p>No. log4j is not reliable. It is a best-effort
	<em>fail-stop</em> logging system.
	</p>

	<p>By fail-stop, we mean that log4j will not throw unexpected
	exceptions at run-time potentially causing your application to
	crash. <b>If for any reason, log4j throws an uncaught exception,
	please send an email to the <a href="mailto:log4j-user@logging.apache.org">log4j-user@logging.apache.org</a>
	mailing list</b>. Uncaught exceptions are handled as serious bugs
	requiring immediate attention.
	</p>

	<p>Moreover, log4j will not revert to System.out or System.err
	when its designated output stream is not opened, is not writable or
	becomes full. This avoids corrupting an otherwise working program by
	flooding the user's terminal because logging fails. However, log4j
	will output a single message to System.err indicating that logging can
	not be performed.
	</p><table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a1.3">What are the prerequisites for log4j?</a></dt>
<dd>
	  <p>Log4j 1.2.8 and earlier are compatible with JDK 1.1.x and later, later versions
          of log4j 1.2 are compatible with JDK 1.2 and later.
	 </p>

	  <p>The DOMConfigurator is based on the DOM Level 1
	  API. The DOMConfigurator.configure(Element) method will work
	  with any XML parser that will pass it a DOM tree.
	 </p>
	  <p>The DOMConfigurator.configure(String filename) method and its
	  variants require a JAXP compatible XML parser, for example <a href="http://xml.apache.org/">Xerces</a> or Sun's
	  parser. Compiling the DOMConfigurator requires the presence of a
	  JAXP parser in the classpath.
	 </p>

	  <p>The <code>org.apache.log4j.net.SMTPAppender</code>
	  relies on the <a href="http://java.sun.com/products/javamail/">JavaMail
	  API</a>. It has been tested with JavaMail API version
	  1.2. The JavaMail API requires the <a href="http://java.sun.com/beans/glasgow/jaf.html">JavaBeans
	  Activation Framework</a> package.
	 </p>

	  <p>The <code>org.apache.log4j.net.JMSAppender</code>
	  requires the presence of the JMS API as well as JNDI.
	 </p>

	  <p>log4j test code relies on the <a href="http://www.junit.org">JUnit</a> testing framework.
	 </p>
             <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a1.4">What are the features of log4j?</a></dt>
<dd>
	  <p>log4j is optimized for speed.</p>

	  <p>log4j is based on a named logger hierarchy.</p>

	  <p>log4j is fail-stop. However, altough it certainly
	  strives to ensure delivery, log4j does not guarantee that
	  each log statement will be delivered to its destination.
	 </p>

	  <p>log4j is thread-safe.</p>

	  <p>log4j is not restricted to a predefined set of
	  facilities.</p>

	  <p>Logging behavior can be set at runtime using a
	  configuration file. Configuration files can be property
	  files or in XML format. </p>

	  <p>log4j is designed to handle Java Exceptions from the
	  start.</p>

	  <p>log4j can direct its output to a file, the console,
	  an <code>java.io.OutputStream</code>,
	  <code>java.io.Writer</code>, a remote server using TCP, a
	  remote Unix Syslog daemon, to a remote listener using JMS,
	  to the NT EventLog or even send e-mail. </p>

	  <p>log4j uses 6 levels, namely TRACE, DEBUG, INFO, WARN, ERROR and
	  FATAL.
	 </p>

	  <p>The format of the log output can be easily changed by
	  extending the <code>Layout</code>
          class. </p>

	  <p>The target of the log output as well as the writing
	  strategy can be altered by implementations of the
	  <code>Appender</code> interface. </p>

	  <p>log4j supports multiple output appenders per logger.
	 </p>

	  <p>log4j supports internationalization.</p>
             <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a1.5">Is there example code for using log4j?</a></dt>
<dd>
	<p>See the <code>examples/</code> directory.</p>
      <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a1.6">What documentation should I read to learn more about
      log4j?</a></dt>
<dd><p>Make sure to read the <a href="manual.html">short
	manual</a>. It is also recommended to you read <a href="https://www.qos.ch/shop/products/log4j/log4j-Manual.jsp">The complete
	log4j manual</a> which is much more detailed and up to
	date. Both documents were written by Ceki Gülcü.
	</p><table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a1.7">Is log4j thread-safe?</a></dt>
<dd>
	<p>Yes, log4j is thread-safe. Log4j components are designed to
	be used in heavily multithreaded systems.</p>

      <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a1.8">What does log output look like?</a></dt>
<dd>
 	<p>The log output can be customized in many ways. Moreover,
	one can completely override the output format by implementing
	one's own Layout.
	</p>

	<p>Here is an example output using <em>PatternLayout</em> with
	the conversion pattern <b>"%r [%t] %-5p %c{2} %x - %m%n"</b>
	</p>

	<pre class="screen_output">
176 [main] INFO  examples.Sort - Populating an array of 2 elements in reverse order.
225 [main] INFO  examples.SortAlgo - Entered the sort method.
262 [main] DEBUG SortAlgo.OUTER i=1 - Outer loop.
276 [main] DEBUG SortAlgo.SWAP i=1 j=0 - Swapping intArray[0] = 1 and intArray[1] = 0
290 [main] DEBUG SortAlgo.OUTER i=0 - Outer loop.
304 [main] INFO  SortAlgo.DUMP - Dump of interger array:
317 [main] INFO  SortAlgo.DUMP - Element [0] = 0
331 [main] INFO  SortAlgo.DUMP - Element [1] = 1
343 [main] INFO  examples.Sort - The next log statement should be an error message.
346 [main] ERROR SortAlgo.DUMP - Tried to dump an uninitialized array.
        at org.log4j.examples.SortAlgo.dump(SortAlgo.java:58)
        at org.log4j.examples.Sort.main(Sort.java:64)
467 [main] INFO  examples.Sort - Exiting main method.
	</pre>

	<p>The first field is the number of milliseconds elapsed since
	the start of the program. The second field is the thread
	outputting the log statement. The third field is the level of
	the log statement. The fourth field is the rightmost two
	components of the logger making the log request. The fifth
	field (just before the '-') is the <em>nested diagnostic
	context</em> (NDC). Note the nested diagnostic context may be
	empty as in the first two statements. The text after the '-'
	is the message of the statement.
	</p>
          <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a1.9">Why should I use log4j when JDK 1.4 already ships with a
      logging API?</a></dt>
<dd>

        <p>
        Although both APIs are conceptually similar, the log4j API is
        significantly more flexible and offers many more features, too
        numerous to be listed here. You will discover that the
        additional features and flexibility turn out to be
        indispensable in the context of a mission-critical
        application.
       </p>

        <p>The open and collaborative way in which log4j is developped
        ensures that it continues to preserve and even widen its
        competitive edge. At some point, input from bright developers
        from all over the world is bound to make a difference.
       </p>
        <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a2.1">What are <em>Loggers</em>?</a></dt>
<dd>

	<p>Lggers lie at the heart of log4j. Loggers define a hierarchy and give
	the programmer <em>run-time</em> control on which statements are
	printed or not.
	</p>

	<p>Loggers are assigned levels. A log statement is printed
	depending on its level <em>and</em> its logger.
	</p>

	<p>Make sure to read the <a href="manual.html">log4j manual</a>
	for more information.
	</p>
          <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a2.2">How can I change log behavior at runtime?</a></dt>
<dd>
	<p>Log behavior can be set using configuration files which are parsed
	at runtime. Using configuration files the programmer can define
	loggers and set their levels.
	</p>

	<p>The <code>PropertyConfigurator</code> defines a particular format
	of a configuration file. See also the <code>examples/Sort.java</code>
	example and associated configuration files.
	</p>

	<p>Configuration files can be specified in XML. See
	<code>log4j.dtd</code> and
	<code>org.log4j.xml.DOMConfigurator</code> for more details.
	</p>

	<p>See the various Layout and Appender components for specific
	configuration options.
	</p>

	<p>In addition to configuration files, the user may disable all
	messages belonging to a set of levels. See next item.
	</p>

             <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a2.3">What is the fastest way of (not) logging?</a></dt>
<dd>
	<p> For some logger <code>l</code>, writing,
	</p>

	<pre class="source">
 l.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));
	</pre>

	<p>incurs the cost of constructing the message parameter, that is
	converting both integer <code>i</code> and <code>entry[i]</code> to a
	String, and concatenating intermediate strings. This, regardless of
	whether the message will be logged or not.
	</p>

	<p>If you are worried about speed, then write</p>
	<pre class="source">
   if(l.isDebugEnabled()) {
     l.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));
   }
	</pre>
    <p>or using LogMF from the extras companion write</p>
    <pre class="source">
    LogMF.debug(logger, "Entry number: {0} is {1}", i, entry[i]);
   </pre>

    <p>This way you will not incur the cost of parameter
	construction if debugging is disabled for logger
	<code>l</code>. On the other hand, if the logger is debug
	enabled, you will incur the cost of evaluating whether the
	logger is enabled or not, twice: once in
	<code>debugEnabled</code> and once in <code>debug</code>.
	This is an insignificant overhead since evaluating a logger
	takes less than 1% of the time it takes to actually log a
	statement.
	</p>
<table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a2.4">Are there any suggested ways for naming loggers?</a></dt>
<dd>
	<p>Yes, there are.</p>

	<p>You can name loggers by <strong>locality</strong>. It turns out
	that instantiating a logger in each class, with the logger name
	equal to the fully-qualified name of the class, is a useful and
	straightforward approach of defining loggers. This approach has
	many benefits:
	</p>

	<ul>
	  <li>It is very simple to implement.</li>

	  <li>It is very simple to explain to new developers.</li>

	  <li>It automatically mirrors your application's own modular design.
	 </li>
	  <li>It can be further refined at will.</li>

	  <li>Printing the logger automatically gives information on the locality
	  of the log statement.	 </li>
	</ul>

	<p>However, this is not the only way for naming loggers. A
	common alternative is to name loggers by <strong>functional
	areas</strong>. For example, the "database" logger, "RMI"
	logger, "security" logger, or the "XML" logger.
	</p>

	<p>You may choose to name loggers by functionality and
	subcategorize by locality, as in "DATABASE.com.foo.some.package.someClass" or
	"DATABASE.com.foo.some.other.package.someOtherClass".
	</p>

	<p><em>You are totally free in choosing the names of your
	loggers.</em> The log4j package merely allows you to manage your
	names in a hierarchy.  However, it is your responsibility to define
	this hierarchy.
	</p>

	<p>Note by naming loggers by locality one tends to name things by
	functionality, since in most cases the locality relates closely to
	functionality.
	</p>
             <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a2.5">How do I get the fully-qualified name of a class in a static block?</a></dt>
<dd>
	<p>You can easily retrieve the fully-qualified name of a class in a
	static block for class X, with the statement
	<code>X.class.getName()</code>. Note that <code>X</code> is the class
	name and not an instance.  The <code>X.class</code> statement does
	<i>not</i> create a new instance of class <code>X</code>.
	</p>

	<p>Here is the suggested usage template:</p>

	<pre class="source">
package a.b.c;

public class Foo {
  final static Logger logger = Logger.getLogger(Foo.class);
  ... other code

}
	</pre>
             <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a2.6">Can the log output format be customized? </a></dt>
<dd>
 	<p>Yes, you can extend the <code>Layout</code> class to create
	you own customized log format. Appenders can be parameterized
	to use the layout of your choice.
	</p>
<table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a2.7">What are the configurable options for <code>FooBarAppender</code>?</a></dt>
<dd>
	<p>Log4j uses JavaBeans style configuration.</p>

	<p>Thus, any setter method in <code>FooBarAppender</code>
	corresponds to a configurable option. For example, in <a href="apidocs\org\apache\log4j\RollingFileAppender.html"><code>RollingFileAppender</code></a>
	the <a href="apidocs/org/apache/log4j/RollingFileAppender.html#setMaxBackupIndex(int)"><code>setMaxBackupIndex(int
	maxBackups)</code></a> method corresponds to the
	<code>maxBackupIndex</code> option. The first letter of the
	option can be upper case, i.e.  <code>MaxBackupIndex</code>
	and <code>maxBackupIndex</code> are equivalent but not
	<code>MAXBACKUPIndex</code> nor <code>mAXBackupIndex</code>.
	</p>

	<p>Layouts options are also defined by their setter methods. The same goes
	for most other log4j components.
	</p>
    <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a2.8">What is the recommended way of migrating from
      java.util.logging to log4j?</a></dt>
<dd>

	<p>We suggest to just use global file search/replace.  You should be able
	to replace all the "java.util.Logger" references with
	"org.apache.log4j.Logger", and you should be on your way.
	</p>

	<p>If you're on a Win32 platform, we recommend <a href="http://www.textpad.com/">Textpad</a>. You can use the
	CTRL+SHIFT+O to open all *.java files from a directory including all
	its sub-directories, and then use the search/replace function to
	replace in all files, and then CTRL+SHIFT+S to save all.  Should take
	about 60 seconds!  :)
	</p>
    <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a2.9">Is it possible to direct log output to
      different appenders by level? </a></dt>
<dd>
	<p>Yes it is. Setting the <b>Threshold</b> option of any appender
	extending <a href="api/org/apache/log4j/AppenderSkeleton.html">AppenderSkeleton</a>,
	(most log4j appenders extend AppenderSkeleton) to filter out all log
	events with <em>lower</em> level than the value of the threshold
	option.
	</p>

	<p>For example, setting the threshold of an appender to DEBUG
	also allow INFO, WARN, ERROR and FATAL messages to log along
	with DEBUG messages. This is usually acceptable as there is
	little use for DEBUG messages without the surrounding INFO,
	WARN, ERROR and FATAL messages. Similarly, setting the
	threshold of an appender to ERROR will filter out DEBUG, INFO
	and WARN messages but not ERROR or FATAL messages.
	</p>

	<p>This policy usually best encapsulates what the user
	actually wants to do, as opposed to her mind-projected
	solution.
	</p>
	<p>See <i>examples/sort4.lcf</i> for an example threshold
	configuration.</p>

	<p>If you must filter events by exact level match, then you can
	attach a <a href="apidocs/org/apache/log4j/varia/LevelMatchFilter.html">LevelMatchFilter</a>
	to any appender to filter out logging events by exact level match.
	</p>
    <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a2.10">What does the Windows NT Event Viewer complain about
      missing descriptions for my event messages when I use the
      <code>NTEventLogAppender</code>?</a></dt>
<dd>
    <p>The NT Event Viewer relies on <i>message resource</i> DLLs
	to properly view an event message.  The NTEventLogAppender.dll
	contains these message resources, but that DLL must be copied
	to %SYSTEMROOT%\SYSTEM32 for it to work properly.
	</p>
      <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a2.11">Why can't I map my logger names to the loggers that
      appear in the NT Event Log when I use the
      NTEventLogAppender?</a></dt>
<dd>
	<p>Unfotunately, the logger names are hardcoded within the
	message resource DLL (see previous question about
	NTEventLogAppender), so there isn't any easy way to override
	those dynamically... in fact, I don't think it's possible to
	do it, as you'd have to modify the DLL resources for every
	application. Since most native applications don't use the
	Logger column anyway...
	</p>
    <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a2.12">Are there suggested approaches for logging in JSP pages?</a></dt>
<dd>
        <p>
        The suggested approach depends on your design requirements.  If you or
        your organization has no constraints on the use of Java in JSP pages,
        simply use log4j normally in <code>&lt;% ... %&gt;</code> statements
        as indicated in the Short Manual and the rest of the documentation.
       </p>
        <p>
        However, if your design calls for a minimum amount of Java in your JSP
        pages, consider using the
        <a href="http://jakarta.apache.org/taglibs/doc/log-doc/intro.html">Log Taglib</a>
        from the Jakarta Taglibs project.  It provides logging JSP tags that invoke
        log4j.
       </p>
    <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a3.1">Can the outputs of multiple client request go to
      different log files?</a></dt>
<dd>
	<p>Many developers are confronted with the problem of
	distinguishing the log output originating from the same class
	but different client requests. They come up with ingenious
	mechanisms to fan out the log output to different files. In
	most cases, this is not the right approach.
	</p>

	<p>It is simpler to use a nested diagnostic context
	(NDC). Typically, one would <em>NDC.push()</em> client
	specific information, such as the client's hostname, ID or any
	other distinguishing information when starting to handle the
	client's request. Thereafter, log output will automatically
	include the nested diagnostic context so that you can
	distinguish logs from different client requests even if they
	are output to the same file.
	</p>

	<p>See the <code>NDC</code> and the <code>PatternLayout</code>
	classes for more information. The <code>NumberCruncher</code>
	example shows how the NDC can be used to distinguish the log
	output from multiple clients even if they share the same log
	file.
	</p>

	<p>For select applications, such as virtual hosting
	web-servers, the NDC solution is not sufficient. As of version
	0.9.0, log4j supports multiple hierarchy trees. Thus, it is
	possible to log to different targets from the same logger
	depending on the current context.
	</p>
    <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a3.2">Logger instances seem to be create only. Why isn't
      there a method to remove logger instances?</a></dt>
<dd>
	<p>It is quite nontrivial to define the semantics of a
	"removed" logger escecially if it is still referenced by the
	user. Future releases <em>may</em> include a remove method in
	the Logger class.</p><table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a3.3">How do I get multiple process to log to the same file?</a></dt>
<dd>
	<p>You may have each process log to a
	<a href="apidocs/org/apache/log4j/net/SocketAppender.html"><code>SocketAppender</code></a>.
	The receiving
	<a href="apidocs/org/apache/log4j/net/SocketServer.html"><code>SocketServer</code></a>
	(or
	<a href="apidocs/org/apache/log4j/net/SimpleSocketServer.html"><code>SimpleSocketServer</code></a>)
	can receive all the events and send them to a single
	log file.
	</p>
     <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a3.4">How about the timesamps of events generated by multiple
      processes across multiple hosts (possibly across multiple
      timezones)?</a></dt>
<dd>
	<p>The timestamp is created when the logging event is created.
	That is so say, when the <code>debug</code>,
	<code>info</code>, <code>warn</code>, <code>error</code> or
	<code>fatal</code> method is invoked.  Thus, the timestamp is
	unaffected by the time at which event arrive at a remote
	socket server.
	</p>

	<p>Timestamps are stored in UTC format inside the
	event. Consequently, when displayed or written to a log file,
	timestamps appear in the same timezone as the host displaying
	or creating the logfile.  Note that because the clocks of
	various machines may not be synchronized, there may be
	timestamp inconsistencies between events generated on
	different hosts.  The EnhancedPatternLayout in the extras companion
    supports explicit specification of the timezone using a pattern like
    "%d{HH:mm}{GMT}".
   </p>
    <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a3.5">Why can't log4j find my properties file in a J2EE or WAR
      application?</a></dt>
<dd>
	<p>The short answer: the log4j classes and the properties file
	are not within the scope of the same classloader.
	</p>

	<p>The long answer (and what to do about it): J2EE or Servlet
	containers utilize Java's class loading system.  Sun changed
	the way classloading works with the release of Java 2.  In
	Java 2, classloaders are arranged in a hierarchial
	parent-child relationship.  When a child classloader needs to
	find a class or a resource, it first delegates the request to
	the parent.
	</p>

	<p>Log4j only uses the default <code>Class.forName()</code>
	mechanism for loading classes.  Resources are handled
	similarly.  See the documentation for
	<code>java.lang.ClassLoader</code> for more details.
	</p>

	<p>So, if you're having problems, try loading the class or
	resource yourself.  If you can't find it, neither will
	log4j. ;)
	</p><table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a3.6">Is there a way to get log4j to automatically reload a
      configuration file if it changes?</a></dt>
<dd>

	<p>Yes.  Both the DOMConfigurator and the PropertyConfigurator support
	automatic reloading through the <code>configureAndWatch</code> method.
	See the API documentation for more details.
	</p>


	<p>Because the <code>configureAndWatch</code> launches a
	separate wathdog thread, and because there is no way to stop
	this thread in log4j 1.2, the <code>configureAndWatch</code>
	method is unsafe for use in J2EE envrironments where
	applications are recycled.
	</p><table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a4.1">Why should I donate my extensions to log4j back to the
      project?</a></dt>
<dd>
	<p>Contrary to the GNU Public License (GPL) the Apache
	Software License does not make any claims over your
	extensions. By extensions, we mean totally new code that
	invokes existing log4j classes. <em>You are free to do
	whatever you wish with your proprietary log4j extensions.</em>
	In particular, you may choose to never release your extensions
	to the wider public.
	</p>

	<p>We are very careful not to change the log4j client API so
	that newer log4j releases are backward compatible with
	previous versions. We are a lot less scrupulous with the
	internal log4j API. Thus, if your extension is designed to
	work with log4j version <code>n</code>, then when log4j
	release version <code>n+1</code> comes out, you will probably
	need to adapt your proprietary extensions to the new release.
	</p>

	<p>Thus, you will be forced to spend precious resources in
	order to keep up with log4j changes. This is commonly referred
	to as the "stupid-tax."  By donating the code and making it
	part of the standard distribution, you save yourself the
	unnecessary maintenance work.
	</p>

	<p>If your extensions are useful then someone will eventually
	write an extension providing the same or very similar
	functionality.  Your development effort will be wasted. Unless
	the proprietary log4j extension is business critical, there is
	little reason for not donating your extensions back to the
	project.
	</p><table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="a4.2">What should I keep in mind when contributing code?</a></dt>
<dd>
	<ol>

	  <li>
	    <p>Write a test case for your contribution.</p>

	    <p>There is nothing more irritating than finding the bugs
	    in debugging (i.e. logging) code. Writing a test case
	    takes some effort but is crucial for a widely used library
	    such as log4j. Writing a test case will go a long way in
	    earning you the respect of fellow developers. See the
	    tests/ directory for exiting test cases.
	   </p>
	 </li>


	  <li>
	    <p>Stick to the existing indentation style even if you hate it.</p>

	    <p>Alternating between indentation styles makes it hard to
	    understand the source code. Make it a little harder on
	    yourself but easier on others.
	   </p>

	    <p>Log4j has adopted a rather conservative approach by
	    following the <a href="http://java.sun.com/docs/codeconv/">Code Conventions
	    for the JavaTM Programming Language</a>. <b>We use 2 (two)
	    spaces for indentation and no tabs.</b>
	   </p>
	 </li>

	  <li>
	    <p>Please do not both modify the code and change the
	    indentation in a single commit.</p>

	    <p>If you change the code and reformat it at the same time
	    and then commit, the commit notification message will be
	    hard to read. It will contain many diffs associated with
	    the reformatting in addition to logical changes.
	   </p>

	    <p>If you must reformat and change the code, then perform
	    each step separately. For example, reformat the code and
	    commit. Following that, you can change the logic and
	    commit. The two steps can be performed in the reverse
	    order just as well. You can first change the logic and
	    commit and only later reformat and commit.
	   </p>

	 </li>
	  <li>
	    <p>Make every effort to stick to the JDK 1.1 API.</p>

	    <p>One of the important advantages of log4j is its
	    compatibility with JDK 1.1.x.
	   </p>
	 </li>

	  <li>
	    <p>Always keep it simple, small and fast when
	    possible.</p>

	    <p>It's all about the application not about logging.</p>
	 </li>

	  <li>
	    <p>Identify yourself as a contributor at the top of the
	    relevant file.
	   </p>
	 </li>
	  <li>
	    <p>Take responsibility for your code.</p>

	    <p>Authoring software is very much like running a marathon. It
	    takes time and endurance.
	   </p>
	 </li>
	  <li>
	    <p>Did we mention sticking with the indentation style?</p>
	 </li>
	  <li><p>Did we mention writing test cases?</p>
	 </li>

	</ol>
      <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="duplicate-messages">Why am I getting multiple copies of messages in my log file?</a></dt>
<dd>
	    <p>There are several reasons this can occur:
		<ul>
			<li>Repeated configuration of log4j:  By default, each call to 
			PropertyConfigurator.configure or DOMConfigurator.configure is
			culmulative.  If your configuration file defines a file appender,
			calling PropertyConfigurator.configure three times will create
			three distinct instances and connect each of them to the specified logger.</li>
			<li>Attaching the same appender to multiple loggers: if an appender is
			attached to the root logger and child logger, then any message
			sent to the child logger will go to the appender twice (unless 
			additivity is set to false).</li>
		</ul></p>
	  <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="custom-level">How do I add a custom level?</a></dt>
<dd>
          <p>It is possible, but rarely appropriate.  The
          request is commonly for a level named something like "audit"
          that doesn't obviously fit in the progression "trace", "debug",
          "info", "warn", "error" and "fatal".  In that case, the request
          for a level is really a request for a mechanism to specify
          a different audience.  The appropriate mechanism is to use a distinct
          logger name (or tree) for "audit" related messages.</p>
        <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="unload">Why does log4j throw a NullPointerException or
              print a message about NOPLoggerRepository
              when shutting down or restarting under Tomcat or during a shutdown
              hook?</a></dt>
<dd><p>Tomcat will, by default,
             clear all static members when unloading classes, however
             this process can trigger initialization of classes which may
             then call a class that has been cleared resulting in a
             NullPointerException or some undesirable behavior.
             Bug <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=40212">40212</a>)
             describes the problem in detail and has a patch which at this writing
              has not been applied to Tomcat.  Glassfish had a similar problem
             and accepted the patch.</p>

             <p>The following are recommended to avoid this problem:
                 <ol>
                     <li>Set the org.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES
                         system property to false.</li>
                     <li>Apply the patch from bug <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=40212">40212</a>
                         or upgrade to a version that has that patch applied.</li>
                     <li>Upgrade to log4j 1.2.16 or later to better defend against class loader attack
                         or provide a better diagnostic message when it does occur.</li>
                </ol>
            </p>

            <p>It is impossible for log4j to defend against all attacks on
                its internal state by a class loader.  There is a limit to
                the defensive measures that will be incorporated.</p>

             <p>For more background, see bugs
              <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=40212">40212</a>,   
              <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=41939">41939</a>,
              <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=43867">43867</a>,
              <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=40159">40159</a>,
              <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=43181">43181</a>,
              <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=41316">41316</a> and
              <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=37956">37956</a>.
            </p>
          <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="rfa">Why isn't my rolling file appender properly rolling files or why does
              logging events get written to the old log file?</a></dt>
<dd>Most commonly this is due to multiple appenders attempting to
          use the same file path and most likely by having multiple independent 
          instances of log4j read the same configuration file, however having the log file
          open by another process (an editor, backup utility) can also interfere with rolling.
          No provided file appender is reliable when multiple instances are writing to
          the same file path and java.io provides no mechanism to coordinate writing
          between JVM's.<table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="noconfig">
              Why do I see a warning about "No appenders found for logger" and
              "Please configure log4j properly"?
          </a></dt>
<dd>
            This occurs when the default configuration files log4j.properties and
            log4j.xml can not be found and the application performs no explicit configuration.
            log4j uses Thread.getContextClassLoader().getResource() to locate the default
            configuration files and does not directly check the file system.
            Knowing the appropriate location to place log4j.properties or log4j.xml
            requires understanding the search strategy of the class loader in use.
            log4j does not provide a default configuration since output to the console
            or to the file system may be prohibited in some environments.  Also see
            <a href="#a3.5">FAQ: Why can't log4j find my properties in a J2EE or WAR application?</a>.
          <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
</dd>
<dt><a name="sysprops">What system properties are checked by log4j?</a></dt>
<dd>
              <dl>
                  <dt>log4j.debug</dt>
                  <dd>If true, log4j will output internal debugging messages to the console.</dd>
                  <dt>log4j.defaultInitOverride</dt>
                  <dd>If true, log4j will not perform default initialization,
                      that is check for log4j.properties or log4j.xml, at the first logging request.</dd>
                  <dt>log4j.configuration</dt>
                  <dd>URL for default initialization configuration file.</dd>
                  <dt>log4j.configurationClass</dt>
                  <dd>Class name for configurator to process default initialization configuration file.</dd>
                  <dt>log4j.ignoreTCL</dt>
                  <dd>If true, the thread class loader will be ignored when loading classes.</dd>
             </dl>
              <p>The SMTPAppender may be influenced by mail.smtp and mail.smtps system properties.</p>
          <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table></dd>
</dl>

      </div>
    </div>
    <div class="clear">
      <hr/>
    </div>
    <div id="footer">
      <div class="xright">&#169;  
          1999-2010
    
          Apache Software Foundation
          
  

  
    
  
  
    
  </div>
      <div class="clear">
        <hr/>
      </div>
    </div>
  </body>
</html>
